Movie Controller Actions(IM: QC)

Inside Macintosh: QuickTime Components /: Chapter 2 - Movie Controller Components / Movie Controller Components Reference

Movie Controller Actions
This section discusses actions, which are integer constants (defined by the mcAction data type) used by movie controller components. Applications that use movie controller components can invoke these actions by calling the MCDoAction function,
which is described on page 2-46. If your application includes an action filter function, that function may receive any of these actions (see the discussion of the MCSetActionFilterWithRefCon function on page 2-47 for more information about action filter functions).
Your action filter function should refer any actions that you do not want to handle back to the calling movie controller component. Your function refers actions back to the movie controller component by returning a value of false. If your function returns a value of true, the movie controller component performs no further processing for the action.
If you use any Movie Toolbox functions that modify the movie in your action filter function, be sure to call the MCMovieChanged function (described on page 2-49).
enum {
   mcActionIdle                  = 1,  /* give event-processing time to 
                                          movie controller */
   mcActionDraw                  = 2,  /* send update event to movie
                                          controller */
   mcActionActivate              = 3,  /* activate movie controller */
   mcActionDeactivate            = 4,  /* deactivate controller */
   mcActionMouseDown             = 5,  /* pass mouse-down event */
   mcActionKey                   = 6,  /* pass key-down or auto-key event */
   mcActionPlay                  = 8,  /* start playing movie */
   mcActionGoToTime              = 12, /* move to specific time in a movie */
   mcActionSetVolume             = 14, /* set a movie's volume */
   mcActionGetVolume             = 15, /* retrieve a movie's volume */
   mcActionStep                  = 18, /* play a movie a specified number
                                          of frames at a time */
   mcActionSetLooping            = 21, /* enable or disable looping */
   mcActionGetLooping            = 22, /* find out if movie is looping  */
   mcActionSetLoopIsPalindrome   = 23, /* enable palindrome looping */
   mcActionGetLoopIsPalindrome   = 24, /* find out if palindrome looping
                                          is on */
   mcActionSetGrowBoxBounds      = 25, /* set limits for resizing a movie */
   mcActionControllerSizeChanged = 26, /* user has resized movie 
                                          controller */
   mcActionSetSelectionBegin     = 29, /* start time of movie's current
                                          selection */
   mcActionSetSelectionDuration  = 30, /* set duration of movie's current
                                          selection */
   mcActionSetKeysEnabled        = 32, /* enable or disable keystrokes for
                                          movie */
   mcActionGetKeysEnabled        = 33, /* find out if keystrokes are 
                                          enabled */
   mcActionSetPlaySelection      = 34, /* constrain playing to the current
                                          selection */
   mcActionGetPlaySelection      = 35, /* find out if movie is constrained to
                                           playing within selection */
   mcActionSetUseBadge           = 36, /* enable or disable movie's
                                           playback badge */
   mcActionGetUseBadge           = 37, /* find out if movie controller is
                                          using playback badge */
   mcActionSetFlags              = 38, /* set movie's control flags */
   mcActionGetFlags              = 39, /* retrieve movie's control flags */
   mcActionSetPlayEveryFrame     = 40, /* instruct controller to play all
                                          frames in movie */
   mcActionGetPlayEveryFrame     = 41, /* find out if controller is playing
                                          every frame in movie */
   mcActionGetPlayRate           = 42, /* determine playback rate */
   mcActionShowBalloon           = 43, /* find out if controller wants to
                                          display Balloon Help */
   mcActionBadgeClick            = 44, /* user clicked movie's badge */
   mcActionMovieClick            = 45, /* user clicked in movie *
   mcActionSuspend               = 46, /* suspend event received */
   mcActionResume                = 47  /* resume event received */
typedef short mcAction;
};
The action descriptions that follow are divided into those used by your application and those received by your action filter.
Actions for Use by Applications

mcActionIdle
Your application can use this action to grant event-processing time to a movie controller.

There are no parameters for this action.
mcActionDraw
Your application can use this action to send an update event to a movie controller.

The parameter for this action is a pointer to a window.
mcActionActivate

Your application can use this action to activate a movie controller.

There are no parameters for this action.
mcActionDeactivate
Your application can use this action to deactivate a movie controller.

There are no parameters for this action.
mcActionMouseDown
Your application can use this action to pass a mouse-down event to a movie controller.

The parameter data must contain a pointer to an event structure--the message field in the event structure must specify the window in which the user clicked.
mcActionKey
Your application can use this action to pass a key-down or auto-key event to a movie controller.

The parameter data must contain a pointer to an event structure that describes the key event.

Your action filter function receives this action when the movie controller has received a key-down or auto-key event.
mcActionPlay

Your application can use this action to start or stop playing a movie.

The parameter data must contain a fixed value that indicates the rate
of play. Values greater than 0 correspond to forward rates; values less than 0 play the movie backward. A value of 0 stops the movie.
mcActionGotoTime
Your application can use this action to move to a specific time in a movie.

The parameter data must contain a pointer to a time structure that specifies the target position in the movie.
mcActionSetVolume
Your application can use this action to set a movie's volume.

The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range
from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionGetVolume
Your application can use this action to determine a movie's volume.

The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range
from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionStep
Your application can use this action to play a movie while skipping a specified number of frames at a time.

The parameter data must contain a long integer value that specifies the number of steps (that is, the frames and the play direction). Positive values step the movie forward the specified number of frames;
negative values step the movie backward. A value of 0 steps the movie forward one frame.
mcActionSetLooping
Your application can use this action to enable or disable looping for
a movie.

The parameter data must contain a Boolean value--a value of true indicates that looping is to be enabled.
mcActionGetLooping
Your application can use this action to determine whether a movie is looping.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false.
mcActionSetLoopIsPalindrome

Your application can use this action to enable palindrome looping. Palindrome looping causes a movie to play alternately forward and backward. Looping must also be enabled for palindrome looping to
take effect.

The parameter data must contain a Boolean value--a value of true indicates that palindrome looping is to be enabled.
mcActionGetLoopIsPalindrome
Your application can use this action to determine whether palindrome looping is enabled for a movie. Looping must also be enabled for palindrome looping to take effect.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if palindrome looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value
to false.
mcActionSetGrowBoxBounds
Your application can use this action to set the limits for resizing a movie.

The parameter data consists of a rect structure.
mcActionSetSelectionBegin

Your application can use this action to set the start time of a
movie's current selection. After using this action, you must use the mcActionSetSelectionDuration action to set the duration of
the selection.

The parameter data must contain a pointer to a time structure specifying the starting time of the movie's current selection.
mcActionSetSelectionDuration

Your application can use this action to set the duration of a movie's current selection. You can only use this action immediately after the mcActionSetSelectionBegin action.

The parameter data must contain a pointer to a time structure
specifying the ending time of the movie's current selection.

Your action filter function receives this action when the movie controller has received a request to set the movie's current selection duration.
mcActionSetKeysEnabled
Your application can use this action to enable or disable keystrokes
for a movie.

The parameter data must contain a Boolean value--a value of true indicates that keystrokes are to be enabled. By default, this value is
set to false.
mcActionGetKeysEnabled
Your application can use this action to determine whether keystrokes are enabled for a movie controller.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if keystrokes are enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false.
mcActionSetPlaySelection
Your application can use this action to constrain playing to the current selection.

The parameter data must contain a Boolean value--a value of true indicates that playing within the current selection is to be enabled.
mcActionGetPlaySelection
Your application can use this action to determine whether a movie has been constrained to playing within its selection.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if playing is constrained to the current selection. Otherwise, it sets the value to false.
mcActionSetUseBadge
Your application can use this action to enable or disable a movie's playback badge. If a controller's badge is enabled, then the badge is displayed whenever the controller is not visible. When the controller is visible, the badge is not displayed. If the badge is disabled, the badge is never displayed.

The parameter data must contain a Boolean value--a value of true indicates that the playback badge is to be enabled.
mcActionGetUseBadge
Your application can use this action to determine whether a controller is using a badge. If a controller's badge is enabled, then the badge is displayed whenever the controller is not visible. When the controller is visible, the badge is not displayed. If the badge is disabled, the badge is never displayed.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if the controller is using a badge. Otherwise, it sets the value to false.
mcActionSetFlags
Your application can use this action to set a movie's control flags.

The parameter data must contain a long integer that contains the new control flag values. The following flags are defined:
mcFlagSuppressMovieFrame
Controls whether the controller displays a frame around the movie. If this flag is set to 1, the controller does not display a frame around the movie. By default, this flag is set to 0.
mcFlagSuppressStepButtons
Controls whether the controller displays the step buttons. The step buttons allow the user to step the movie forward or backward a frame at a time. If this flag is set to 1, the controller does not display the step buttons. By default, this flag is set to 0.
mcFlagSuppressSpeakerButton
Controls whether the controller displays the speaker button. The speaker button allows the user to control the movie's sound. If this flag is set to 1, the controller does not display the speaker button. By default, this flag is set to 0.
mcActionGetFlags
Your application can use this action to retrieve a movie's control flags.

The parameter data must contain a pointer to a long integer. The movie controller places the movie's control flags into that long integer. The following movie control flags are defined:
mcFlagSuppressMovieFrame
Controls whether the controller displays a frame around the movie. If this flag is set to 1, the controller does not display a frame around the movie. By default, this flag is set to 0.
mcFlagSuppressStepButtons
Controls whether the controller displays the step buttons. The step buttons allow the user to step the movie forward or backward a frame at a time. If this flag is set to 1, the movie controller does not display the step buttons. By default, this flag is set to 0.
mcFlagSuppressSpeakerButton
Controls whether the controller displays the speaker button. The speaker button allows the user to control the movie's sound. If this flag is set to 1, the movie controller does not display the speaker button. By default, this flag is set to 0.
mcFlagsUseWindowPalette
Controls whether the controller manages the palette for the window containing the movie. This ensures that a movie's colors are reproduced as accurately as possible. This flag is particularly useful for movies with custom color tables. If this flag is set to 1, the movie controller does not manage the window palette. By default, this flag is set to 0.
mcActionSetPlayEveryFrame
Your application can use this action to instruct the movie controller to play every frame in a movie. In this case, the movie controller may play the movie at a slower rate than you specify with the mcActionPlay action. However, the controller does not play the movie faster than the movie rate. In addition, the controller does not play the movie's sound tracks.

The parameter data must contain a Boolean value--a value of true instructs the controller to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified.
mcActionGetPlayEveryFrame
Your application can use this action to determine whether the
movie controller has been instructed to play every frame in a movie.
You tell the controller to play every frame by using the mcActionSetPlayEveryFrame action, which is described earlier in this section.

The parameter data must contain a pointer to a Boolean value--the movie controller sets this value to true if the controller has been instructed to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified. Otherwise, the controller sets the value to false.
mcActionSetGrowBoundsBox
The parameter data must contain a pointer to a rectangle--set the rectangle to the boundary coordinates for the movie. If you want to prevent the movie from being resized, supply an empty rectangle (note that enabling or disabling the size box may change the appearance of some movie controllers). By default, movie controllers do not have size boxes. You must use this action to establish a size box for a movie controller.

If the movie controller's boundary rectangle intersects the lower-right corner of your window, your window cannot have a size box.
mcActionGetPlayRate
Your application can use this action to determine a movie's playback
rate. You set the playback rate when you start a movie playing by using the mcActionPlay action.

The parameter data must contain a pointer to a fixed value. The movie controller returns the movie's playback rate in that fixed value. Values greater than 0 correspond to forward rates; values less than 0 play the movie backward. A value of 0 indicates that the movie is stopped.
mcActionBadgeClick
Indicates that the badge was clicked. The parameter is a pointer to a Boolean value. On entry, the Boolean is set to true. Set the Boolean to false if you want the controller to ignore the click in the badge.
mcActionMovieClick
Indicates that the movie was clicked. The parameter is a pointer to an event structure containing the mouse-down event. If you want the controller to ignore the mouse-down event, change the what field of the event structure to a null event.
mcActionSuspend
Indicates that a suspend event has been received. There is no parameter.
mcActionResume
Indicates that a resume event has been received. There is no parameter.
Actions for Use by Action-Filter Functions

mcActionIdle
Your action filter function receives this action when the application has granted null event-processing time to the movie controller.

There are no parameters for this action.
mcActionDraw
Your filter function receives this action when the controller has received an update event.

The parameter for this action is a pointer to a window.
mcActionActivate

Your filter function receives this action when the controller has received an activate or resume event.

There are no parameters for this action.
mcActionDeactivate
Your filter function receives this action when the controller has received a deactivate or suspend event.

There are no parameters for this action.
mcActionMouseDown
Your action filter function receives this action when the movie controller has received a mouse-down event.

The parameter data must contain a pointer to an event structure--the message field in the event structure must specify the window in which the user clicked.
mcActionKey
Your action filter function receives this action when the movie controller has received a key-down or auto-key event.

The parameter data must contain a pointer to an event structure that describes the key event.
mcActionPlay
Your action filter receives this action when the movie controller has received a request to start or stop playing a movie.

The parameter data must contain a fixed value that indicates the rate
of play. Values greater than 0 correspond to forward rates; values less than 0 play the movie backward. A value of 0 stops the movie.
mcActionGotoTime
Your action filter function receives this action when the movie controller has received a request to go to a specified time in the movie.

The parameter data must contain a pointer to a time structure that specifies the target position in the movie.
mcActionSetVolume
Your action filter function receives this action when the movie controller has received a request to set the movie's volume.

The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range
from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionGetVolume
Your action filter function receives this action when the movie controller has received a request to retrieve the movie's volume.

The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range
from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionStep
Your action filter function receives this action when the movie controller has received a request to play a movie while advancing a specified number of frames at a time.

The parameter data must contain a long integer value that specifies the number of steps (that is, the frames and the play direction). Positive values step the movie forward the specified number of frames;
negative values step the movie backward. A value of 0 steps the movie forward one frame.
mcActionSetLooping
Your action filter function receives this action when the movie controller has received a request to turn looping on or off.

The parameter data must contain a Boolean value--a value of true indicates that looping is to be enabled.
mcActionGetLooping
Your action filter function receives this action when the controller has received a request to indicate whether looping is enabled for its movie.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false.
mcActionSetLoopIsPalindrome

Your action filter function receives this action when the movie controller has received a request to turn palindrome looping on or off. Palindrome looping causes a movie to play alternately forward and backward. Looping must also be enabled for palindrome looping to take effect.

The parameter data must contain a Boolean value--a value of true indicates that palindrome looping is to be enabled.
mcActionGetLoopIsPalindrome
Your action filter function receives this action when the controller has received a request to indicate whether palindrome looping is enabled for its movie.

The parameter data must contain a pointer to a Boolean value. The
movie controller sets this value to true if palindrome looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false.
mcActionControllerSizeChanged
Your filter function receives this action when the user has resized the movie controller--the controller component issues this action before it updates the screen, allowing your application to change the controller's location or appearance before the user sees the resized controller.

There are no parameters for this action.
Note
Your application should never use this action.
mcActionSetSelectionBegin

Your action filter function receives this action when the movie controller has received a request to set the movie's current selection start time.

The parameter data must contain a pointer to a time structure specifying the starting time of the movie's current selection.
mcActionSetSelectionDuration
Your action filter function receives this action when the movie controller has received a request to set the movie's current selection duration.

The parameter data must contain a pointer to a time structure
specifying the ending time of the movie's current selection.
mcActionSetKeysEnabled
Your action filter function receives this action when the movie controller has received a request to enable or disable keystrokes.

The parameter data must contain a Boolean value--a value of true indicates that keystrokes are to be enabled. By default, this value is
set to false.
mcActionGetKeysEnabled
Your filter function receives this action when the controller has received a request to indicate whether keystrokes are enabled for its movie.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if keystrokes are enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false.
mcActionSetPlaySelection
Your action filter function receives this action when the movie controller has received a request to constrain playing to the current selection.

The parameter data must contain a Boolean value--a value of true indicates that playing within the current selection is to be enabled.
mcActionGetPlaySelection
Your action filter function receives this action when the movie controller has received a request to indicate whether playing is constrained to the current selection.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if playing is constrained to the current selection. Otherwise, it sets the value to false.
mcActionSetUseBadge
Your action filter function receives this action when the movie controller has received a request to turn the playback badge on or off.

The parameter data must contain a Boolean value--a value of true indicates that the playback badge is to be enabled.
mcActionGetUseBadge
Your action filter function receives this action when the controller has received a request to indicate whether it is using a badge during playback.

The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if the controller is using a badge. Otherwise, it sets the value to false.
mcActionSetFlags
Your action filter function receives this action when the movie controller has received a request to set the movie's control flags .

The parameter data must contain a long integer that contains the new control flag values. The following flags are defined:
mcFlagSuppressMovieFrame
Controls whether the controller displays a frame around the movie. If this flag is set to 1, the controller does not display a frame around the movie. By default, this flag is set to 0.
mcFlagSuppressStepButtons
Controls whether the controller displays the step buttons. The step buttons allow the user to step the movie forward or backward a frame at a time. If this flag is set to 1, the controller does not display the step buttons. By default, this flag is set to 0.
mcFlagSuppressSpeakerButton
Controls whether the controller displays the speaker button. The speaker button allows the user to control the movie's sound. If this flag is set to 1, the controller does not display the speaker button. By default, this flag is set to 0.
mcActionGetFlags
Your action filter function receives this action when the movie controller has received a request to retrieve the movie's control flags.

The parameter data must contain a pointer to a long integer. The movie controller places the movie's control flags into that long integer. The following movie control flags are defined:
mcFlagSuppressMovieFrame
Controls whether the controller displays a frame around the movie. If this flag is set to 1, the controller does not display a frame around the movie. By default, this flag is set to 0.
mcFlagSuppressStepButtons
Controls whether the controller displays the step buttons. The step buttons allow the user to step the movie forward or backward a frame at a time. If this flag is set to 1, the movie controller does not display the step buttons. By default, this flag is set to 0.
mcFlagSuppressSpeakerButton
Controls whether the controller displays the speaker button. The speaker button allows the user to control the movie's sound. If this flag is set to 1, the movie controller does not display the speaker button. By default, this flag is set to 0.
mcFlagsUseWindowPalette
Controls whether the controller manages the palette for the window containing the movie. This ensures that a movie's colors are reproduced as accurately as possible. This flag is particularly useful for movies with custom color tables. If this flag is set to 1, the movie controller does not manage the window palette. By default, this flag is set to 0.
mcActionSetPlayEveryFrame
Your action filter function receives this action when the movie controller has received a request to play every frame in a movie.

The parameter data must contain a Boolean value--a value of true instructs the controller to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified.
mcActionGetPlayEveryFrame
Your action filter function receives this action when the movie controller has received a request to indicate whether it has been instructed to play every frame in a movie.

The parameter data must contain a pointer to a Boolean value--the movie controller sets this value to true if the controller has been instructed to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified. Otherwise, the controller sets the value to false.
mcActionSetGrowBoundsBox
Your action filter function receives this action when the movie controller has received a request to set the limits for resizing the movie.

The parameter data contains a pointer to a rectangle--the rectangle defines the boundary coordinates for the movie. If the rectangle is empty, the application wants to disable the size box. You may change the appearance of your controller in response to such a request.
mcActionShowBalloon
Your action filter function receives this action when the controller wants to display Balloon Help. Your filter function instructs the controller whether to display the Balloon Help. This action allows you to override the movie controller's default Balloon Help behavior.

The parameter data contains a pointer to a Boolean value. Set the value to true to display the appropriate Balloon Help. Otherwise, set the value to false.
Note
Your application should never use this action.